This Users’ Guide is provided for completeness, and because as you use the program some subtle things may occur which would be difficult to understand without this manual. However, in general InterCal is a very simple program with (I hope) an intuitive interface. You should be able to familiarize yourself with all the options in a few minutes simply by running the program and playing around.
Explanations of the implemented calendar systems, and some definitions of terms (such as era), can be found in the accompanying document Calendar System Facts.
2. STARTUP STATE
InterCal has two windows. The main window (described in detail in §3) is always visible. Both its size and position are adjustable. The “date” window (described in §4.4.1) is not visible at startup. Its visibility is controlled by the user. Its size is not adjustable but its position is. The program tries to draw both windows with exactly the same size and position which they had the last time the program was run. If that cannot be done for any reason, the program reverts to its defaults. The default for the main window is near the upper left corner of the main screen, with a size which nearly fills it. However, a maximum size is built in so that the window will never exceed the size necessary to display all of its contents at once. The default for the date window is to be centered on the main screen.
The initial calendar system is Western Historical. The initial secondary calendar system (see below for definition of a secondary calendar) is “none”. The year and month are chosen so that today’s date is visible and selected. Since it is selected, it is highlighted using reverse video.
A variety of Christian, Jewish, and Islamic holidays can be highlighted under user control. The program attempts to use the same settings which were in effect the last time the program was executed. If it cannot do so, it reverts to the defaults.The default is to highlight the following religious holidays/holy days: Western Easter, Christmas, Rosh Hashonah, Yom Kippur, Hanukah, Passover, first day of Ramadan, Islamic New Year, Milad-an-Nabi (birthday of the Prophet), and the start of ‘Id al-Fitr (festival after Ramadan is over). (It may seem strange to most people to highlight Christmas, since it is a fixed feast. But it is only fixed in the Gregorian calendar and its relatives! All Jewish and Islamic holy days are fixed in their respective calendars. Easter and Pentecost are the only truly movable feasts handled by InterCal.) If the current screen is operating in color mode, Christian holidays are shown in yellow, Jewish in blue, and Islamic in red. I chose these colors from among the basic eight colors provided in the very first version of QuickDraw. If the current screen is monochrome, holidays are highlighted using three of the standard patterns found in the system resource file.
3. THE MAIN WINDOW
3.1. Static Calendar System Displays
The main window is divided into several panes: the primary and secondary calendar system labels; the month displayed; the era displayed; the year displayed; and the month calendar.
On the top line at the left, in a static (not editable) text area, the current choice of primary calendar system is displayed. To its right the current choice of secondary system is shown. Most of the rest of the window contents refer to dates in the primary calendar system. The secondary system (if there is one) is used to directly compare dates in one system to the same dates in the other system. See §4.3, “Primary and Secondary Menus”, for more details.
3.2. Month/Era Selection
The next line is in larger type. At the left is the name of the month being displayed. At the right is the era of the displayed month. Both the name of the month and the name of the era are actually entries in popup menus. The user can use the menus to switch to a different month in the same year, or to switch eras while keeping the month and the absolute value of the year the same. These menus are written using the Avant Garde font, which I believe is available on most Macintosh systems.
Immediately to the left and right of the month name/menu are large arrows. They are blue or dark gray depending on your monitor’s color mode. These arrows act like buttons. They can be clicked once, or pressed (click and hold down the mouse). The left-pointing arrow decreases the month, while the right-pointing arrow increases the month. When the mouse is released, the rest of the window is redrawn to match the newly-selected month. It is OK to press so long that the months cycle past a year boundary. The program works correctly even if the era happens to change while pressing a month-changing button.
Thus there are two alternate ways to change months. The pop up menu might be most convenient for jumping from one end of a year to the other, whereas the arrow buttons might be best for moving a few months at a time.
3.3. Year Selection
Centered in the next line down, in medium type, is a box displaying the absolute value of the year. (To determine the sign of the year, you need to look at the era display.) It is surrounded by two arrow buttons. These buttons act similarly to the month buttons described above, except that they decrement or increment the year. The down-pointing arrow at the left decreases the actual value (not the absolute value) of the year. Thus it takes you towards the past. The up-pointing arrow at the right increases the actual value of the year, taking you towards the future.
The arrow buttons are only useful for moving a few years at a time. In order to enable large jumps in time, the year displayed in the box is an editable text field. The idiosyncrasies of editing the text field which specifies the year may be confusing. That is the primary reason I felt it was worth writing this Users’ Guide.
You can select text or place the insertion cursor wherever you want, and then follow normal text editing conventions to adjust the year to almost any value you desire. While you are doing this, the edit menu becomes active, permitting one-step undo/redo, cutting and pasting, and deletion of characters. You signal InterCal that you are finished editing the year by hitting either the Return or the Enter or the Tab key. If you change your mind while editing, the Escape key or Cmd-period ends your editing session and restores the year to the value it had before you started editing.
Editing the year normally leaves the month unaffected. However, luni-solar calendars have years with differing numbers of months and this may force a change of month. For example, if you are in the Jewish calendar displaying Adar I 5755 A.M. and jump to a non-leap-year, such as 5754 A.M., the month will change to Adar. Similarly, jumping from a leap year in the Elliott calendar, while displaying the month of Anthony, to a non-leap-year causes the month to switch to Ericka. It doesn’t matter whether the arrow buttons or the editable text field are used to change years—the same rule applies.
I wanted the user to be able to jump immediately from any year to any other year (within limits specified below) in a single editing step. This led me to a slight problem—namely, the fact that (in keeping with good calendrical conventions) the box is displaying the absolute value of the year. What if the user wants to jump to a year in the other era? What if he/she doesn’t? Of course you could always do the job in two steps, using the era popup and editing the year text box. But that would be inconvenient. I eventually settled on the following rules:
a) If the user simply manipulates the numbers in the year without providing an explicit sign (plus or minus), the era remains the same. As an example, if you are in April 4956 B.C. and edit the year box to read “111193”, you will be taken to April 111193 B.C.
b) If the user explicitly enters a sign immediately before the year (no spaces permitted) the era is forced to agree with the entered sign (which will then disappear from the display). For example, if you are displaying April 4956 B.C. and edit the year to read “+111193” you will be taken to 111193 A.D. In either case [a] or [b], the final year display will read simply “111193”, but the era display in the two cases will be different, as will (usually) the month calendar itself.
3.4 The Month Calendar and Day Selection
3.4.1. The Day Boxes
Most of the main window is taken up by a calendar showing the month selected by the user using the methods described above. Each box in the calendar is either blank or has the day of the month in large bold type in the upper right. If a secondary calendar system has been chosen, there are two lines (small type, right-justified in the box) below the day number showing the date in the secondary system. The first of the two small lines shows the day and month. The second shows the year and era.
If the displayed month contains a holiday which the user has designated for highlighting (see §4.4.2 below) the name of the holiday appears on the next line (left justified). It is possible for holidays to collide (for example, Christmas and Hanukah). In such cases more than one name appears in the box. In case of collision, the highlight colors or patterns appear with the following priority: Christian overrides Jewish which overrides Islamic. This ordering merely reflects the order of checking for holidays in the code. Please do not read any ulterior motives into the ordering—there are none.
If the displayed month includes the selected date (see next subsection) or today’s date, they are also highlighted—always in black and white. The selected date appears in reverse video. Today’s date appears with a light-gray background. On the screen, selection overrides all other highlighting—the selected date always appears in reverse video whether or not it is today’s date or a highlighted holiday. The “today’s date” highlighting overrides holiday highlighting, but not selection. When printing, slightly different rules apply, as explained in detail in §4.1.3 below.
3.4.2. Date Selection
The user may select any displayed date by clicking once in its box. He/she may cause there to be no selected date by clicking on any blank box in the month calendar.
Selecting a date serves two functions. The user may want to mark a date to return to later after exploring other months or years (see §4.4.3). Or you may want to see at a glance that date’s equivalent in all implemented calendars using the date window (see §4.4.1). Causing there to be no selected date serves no apparent function unless the user finds the reverse video box to be aesthetically unappealing, but I had to decide to either ignore clicks in blank boxes or do something. I chose the latter.
There is another way to select a date which does not require the date to be in the current month calendar display. It is described in §4.4.1 below.
4. THE MENU BAR
4.1. File Menu
Three commands on the File menu are always active— Quit, Page Setup…, and Print…. Other commands are visible but inactive. They are there for desk accessories.
4.1.1 Quit
The Quit command saves window size and position information, holiday selections, and print records, then quits the program.
4.1.2 Page Setup Main… or Page Setup JDate…
This command brings up the standard Page Setup dialog for the print manager. InterCal uses and stores two print records, one for each window. (This is done because the main window is best printed in landscape mode, while the date window is best printed in portrait mode.) The print record for the active window is the one you will be modifying when you use this command. The name of the command changes when the active window changes, to remind you of which record you are affecting. After your initial setting up, it is unlikely you will ever need this command unless you switch printers.
4.1.3 Print Main… or Print JDate…
The Print… command’s name on the menu is changed to either Print Main … or Print JDate…, depending on which window is active. The Print Main… command brings up a slightly non-standard print dialog. A check box has been appended which is explained in the following paragraph. The main window must be printed in landscape mode in order to fit on one 8.5 by 11 page. Depending on your printer and driver, you may also need to scale the print (using the Page Setup command) to 90% or 95% of full size. The Print JDate… command brings up the standard print dialog to print the date window.
The added check box, “Color Printer”, appears when you select Print Main…. (The date window has no color in it, and so InterCal doesn’t care whether or not you have a color printer when printing the date window.) Remember that holidays are highlighted in color on a color monitor and using fill patterns on a monochrome monitor. InterCal does the same thing for printers. The problem is that there appears to be no way for an executing program to know whether or not the chosen printer has color capability and is operating in color mode. InterCal relies on the user to specify this information. (Executing programs can detect whether or not the printer driver is color Quickdraw aware. If it is not, then the printer must be black-and-white or at least operating in black-and-white mode. But if it is, the printer might still be black-and-white.)
InterCal stores the user’s choices for this check box, and always presents the most recent choice as the default. If you have chosen a different printer between print requests, this may not be appropriate.
The following differences exist between what you see on the screen and what is printed:
1) There is no inversion (equivalent to reverse video on the screen) on many printers, so the rules for highlighting are changed for printing. Instead of having the highest priority (as it does on the screen), selection has the lowest priority. Therefore, the selected date will appear in black and white reverse video on the printout only if it is not today’s date, not a highlighted holiday, and only if your printer supports inversion.
2) The month and year incrementing/decrementing arrows are not printed.
4.2. Edit Menu
The Edit menu is normally inactive. It is provided primarily for desk accessories. However, it automatically becomes active when the user edits the year field in the main window or the Julian Day field in the Date Window. At that time, the standard edit commands are activated.
4.3. Primary and Secondary Menus
The next two menus are labeled Primary and Secondary. These menus are used to set the calendar systems to be displayed in the main window. The options available in both menus are the implemented calendars, plus a choice of None for the secondary system.
You can change the primary system at any time. The presently-selected primary system is deactivated in the menu, but all other choices are available. If you select as the new primary system a calendar which is currently the secondary one, the program obeys your command and automatically resets the secondary system to “None”.
When you change primary systems, the entire main window is redrawn. The year field and displayed month change according to the following rules. The selected date (if any) is not affected by switching primary systems.
1) If there is a selected date, and if it is being displayed at the time the system switch occurs, the year and month in the new system will be chosen so that the selected date is still displayed.
2) If there is no selected date, or if the selected date is not being displayed at the time of the switch, then InterCal ensures that the newly displayed month includes the internally-maintained date called “Displayed Date”. The “displayed date” is usually (but not necessarily) the first day of the displayed month, and is always somewhere in the displayed month.
These rules ensure that switching primary systems will not transfer you very far in time.
The secondary calendar system can also be changed at any time. (It is set to “None” at program startup.) If there is a secondary system active, each day of the displayed month has its corresponding date in the secondary system written in its box. This feature enables direct comparison of dates in two separate calendar systems, and is one of the primary features for which InterCal was written.
Just as any implemented system can be the primary system, any other system can be the secondary system. The program prevents you (by disabling menu choices) from selecting the current primary system or the current secondary system as the new secondary system. [However, see Reverse Calendars under the Options menu (§4.4.5)].
Switching secondary systems does not alter most of the main window. Only the “fine print” in each day’s box changes.
4.4. The Options Menu
4.4.1. Show Date Window
This menu option is enabled whenever the date window is not visible, either because it is not open or because it is completely hidden behind the main window. This window has an editable text field showing the Julian Day of the selected date. It does not matter whether or not the selected date is presently being displayed in the main window. While editing the Julian Day field, the Escape, Return, Tab, and Enter keys work exactly as in the year text box in the main window.
Below the Julian Day is a table showing the selected date in all implemented calendar systems. Editing the Julian Day field sets or resets the selected date to whatever number you enter. Your entry can be positive, negative, or zero. Here the usual mathematical convention is followed—numbers without an explicit sign are considered to be positive. The new selected date takes effect immediately, and the main window highlighting is updated even though that window is in the background. However, there is no automatic jumping to the new selected date. You still need to use the Jump to Selected menu item for that.
The number you enter for the Julian Day does not have to end in .5 (which corresponds to midnight on the prime meridian). If it does not, the program automatically adjusts your entry to the preceding midnight.
Setting the state of the program such that there is no selected date (by clicking on a blank box in the main window’s month calendar pane) has no effect on the date window. Thus it is more accurate to say that the date window shows the most recently selected date. I thought about ensuring that the date window is closed when there is no selected date, and also of disabling the Show Date Window option in the Options menu. That seemed to me to be the most rational approach. But reading the Macintosh user interface guidelines made me think that such an arrangement violates the guidelines. User feedback on this subject is welcome.
Once open, the date window can be closed by clicking on its close box. If it is entirely surrounded by the main window, it can be hidden by activating the main window.
4.4.2. Holidays…
The Holidays option brings up a modal dialog box which lets the user determine which of the implemented holidays should be highlighted. (The highlighting scheme was described earlier.) The dialog box contains three columns (one each for Christian, Jewish, and Islamic). Within each column there are three radio buttons and a group of check boxes. If the “All …” button is on, every implemented holiday for that religion will be highlighted. If the “No…” button is on, none of them will be highlighted. If the “Checked…” button is on, the check box group is active and individual holidays may be selected or deselected for highlighting. Unless the “Checked…” button is on, the check boxes are deactivated and their settings are ignored by the program. Their values are not updated by clicking on any radio button. This behavior differs noticeably from the behavior of the check boxes in InterCal Versions 1.0 and 1.1. Clicking on OK accepts the new settings. Cancel closes the box without updating the old set of selections.
Regardless of the user’s settings, holidays are not highlighted in the following cases:
1) Christian holidays/holy days in the B.C. era;
2) Jewish holidays/holy days in the B.W. era;
3) Islamic holidays/holy days in the B.H. era.
Some holidays/festivals/observances last for several days or, in the case of Ramadan, an entire month. In such cases, only the first day is highlighted.
The dates of Christmas and Epiphany are calculated in the Western Historical calendar. That is, the Julian calendar dates and rules are used on or before October 4, 1582 A.D. and the Gregorian calendar dates and rules are used after that date. Thus, if your primary calendar is Gregorian in years before 1582, or the Julian in years after 1582, do not be surprised to see Christmas or Epiphany seeming to fall on dates other than December 25 and January 6. I did not bother to have separate Julian and Gregorian choices for these holidays, since they are fixed. Christmas is December 25 and Epiphany is January 6 (Julian in Orthodox Christian churches; Gregorian otherwise).
I do have separate boxes for Julian and Western Easter and Pentecost. “Western” Easter (used by the Roman Catholic and most Protestant churches) uses the old Julian rules for years 1582 and earlier, and the revised Gregorian rules for years 1583 and later. Eastern Orthodox churches are still using the Julian Calendar to determine the dates of all holidays. So “Julian” Easter permits you to see when the Orthodox churches will celebrate Easter, no matter what the year (and similarly for “Julian” Pentecost). You will probably also want to use Julian Easter for determining the holiday dates in Protestant countries during the years after 1582 but before your country of interest switched to the Gregorian calendar. In years 1582 and earlier, the holidays always collide, so InterCal simply uses one holiday label—”Easter” or “Pentecost” as appropriate.
4.4.3 Jump To Selected
Selecting Jump To Selected causes the year and month in the main window to be reset (if necessary) to the month containing the selected date. If there is no selected date, this menu item is disabled.
4.4.4 Return To Today
Selecting Return To Today causes the year and month in the main window to be reset (if necessary) to the month containing today’s date.
4.4.5 Reverse Calendars
Selecting Reverse Calendars switches the roles of the primary and secondary systems. The former primary system becomes the secondary, and vice versa. This item is disabled if there is no secondary system active. Since the months rarely overlap exactly, there have to be some rules for determining which month in the new primary system is displayed. The same rules are used as when a new primary system is chosen under the Primary menu (see §4.3).
5. LIMITATIONS
5.1. Year and Julian Day Ranges
In order to be accurate, the calendar calculations must be performed using integer arithmetic. Since the basic unit is the day, InterCal is limited to dates for which the integer part of the Julian Day can fit into a signed 32-bit integer. Validity checking is performed on the Julian Day box in the Date Window and on the year box in the main window to prevent such dates from occurring. I tried to set the limits a little narrower than actually required. However, the logic is complex in places and the limits on Julian Day numbers and years are not perfectly consistent. Also, it is possible (through use of the arrow buttons on months and years) to defeat the text validation code. If any of these things happens, InterCal should not crash, but will produce some garbage results or may put up an alert box when you don’t expect it. The validation code will not allow the absolute value of Julian Day entries to exceed 2,145,000,000 or the absolute value of year entries to exceed 5,850,000.
(irrelevant note) By pure coincidence, the allowable range of years is similar to, but a little larger than, the repetition period of Easter dates. The Easter cycle in the Gregorian rule is exactly 5,700,000 years long.
5.2 Excess Holiday Collisions
On very rare occasions, three holidays (one Christian, one Jewish, one Islamic) all occur on the same day. It is even theoretically possible for four to collide (both Easters plus a Jewish and an Islamic holiday), although I do not know if such a thing actually happens. Since screen space is limited, since I did not want to induce eye strain in the user, and since triple (or greater) collisions are so rare, I decided not to adjust box sizes or fonts to ensure that the names of all holidays would fit into the same box. Instead, when this happens, holiday names overflow into the box below, marring the appearance of the display. If a triple collision occurs on the bottom row of the display, the title of the third holiday will be partially clipped by the window boundary.
6. KNOWN PROBLEMS
6.1. Exceeding the Long Integer Limit
Instead of relying on crude validation limits on the entered year or Julian Day, InterCal ought to check for the overflow, raise an exception, and issue a warning to the user. Then only actual violations will prevent successful execution, and the user will never see an unexpected year alert box when he has just entered a Julian Day. This improvement is planned for a later version.
6.2. Improperly Displayed Month and Era Popups
Sometimes the month and era popup menus will be truncated at the right. Also, sometimes the popup menus (when activated) appear in 12-point type (the program tries to display then in 24-point). These popup size problems appear to me to be bugs in the Symantec Visual Architect code which initializes the popup menus. At seemingly unpredictable times (but always during startup), it sizes them using the system font instead of the actual font specified in my code. This bug has been reported to Symantec. The problem usually goes away if you simply quit and restart the program. An attempted workaround for this problem was put into Version 1.2. If this problem occurs in any version of InterCal higher than or equal to 1.2, please notify me at the e-mail address in the ReadMe file.
The mark character, which shows which popup item is currently selected, is not properly displayed. This problem also appears to be either a bug or a feature of the Visual Architect code. I know of no work around.
